home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / ada / pager2.zip / PAGER2.DOC < prev    next >
Text File  |  1989-06-17  |  15KB  |  482 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.                                      PAGER2
  7.  
  8.                                 by Richard Conn
  9.  
  10.                   PAGER2 is   a  tool  for  creating  paged  files,
  11.              extracting  the component files from a paged file, and
  12.              scanning  paged  files,   where   a  paged  file  is a
  13.              file  composed  of  one  or  more  files  prefixed  by
  14.              banners.    PAGER2   is  based  in  concept   on   the
  15.              UNPAGE   tool submitted to the Ada Software Repository
  16.              on SIMTEL20 by Mitre Corporation.  
  17.  
  18.                   Paged files   are   convenient   mechanisms   for
  19.              storing  related   files.   They   reduce   cluttering
  20.              in   the  directories  and  simplify the file transfer
  21.              process  by requiring  the  user  to transfer only one
  22.              file  in  order  to  obtain  all  files pertinent to a
  23.              particular  project  or  tool.   Additionally,   paged
  24.              files   are  text  files  which  can  be  handled more
  25.              readily  than  the 8-bit binary images associated with
  26.              other   file   grouping   mechanisms  (see   the  file
  27.              OILBR.DOC     in   the   directory   PD2:<ADA.GENERAL>
  28.              in   the   Ada  Software Repository).  Paged files may
  29.              be  manipulated  by  a  text  editor  if necessary.  
  30.  
  31.                   For these   reasons,   paged   files   have  been
  32.              adopted   as   a   standard  for  file  storage in the
  33.              Ada  Software Repository.  The file type of SRC (as in
  34.              MYFILE.SRC) indicates that a file is paged.  
  35.  
  36.  
  37.  
  38.  
  39.           1.  PAGED FILE FORMAT 
  40.  
  41.                A paged  file  is  a file composed of one or more files
  42.           prefixed  by banners of the form: 
  43.  
  44.                           ::::::::::
  45.                           filename
  46.                           ::::::::::
  47.           or
  48.                           --::::::::::
  49.                           --filename
  50.                           --::::::::::
  51.  
  52.                The first   banner   conforms   to  the  PAGE  standard
  53.           employed  on  UNIX.  The  second  banner is an adaptation of
  54.           the  first  form  which  resembles Ada comments.  The second
  55.           banner  is  convenient   when   the   paged   file  contains
  56.           several   files   associated  with  a particular Ada program
  57.           and  they  are  placed  in  the  paged  file  in compilation
  58.  
  59.  
  60.           Richard Conn                                          Page 1
  61.  
  62.  
  63.                                      PAGER2
  64.  
  65.  
  66.           order.   The  resulting  paged  file  may  then  be compiled
  67.           without being disassembled first.  
  68.  
  69.  
  70.  
  71.  
  72.           2.  PAGER2 COMMANDS 
  73.  
  74.                PAGER2 responds to the following commands: 
  75.  
  76.                 1.  PAGE or P - create a paged file 
  77.  
  78.                 2.  UNPAGE  or U - extract the components of a
  79.                   paged file into their separate files 
  80.  
  81.                 3.  LIST  or  L  -  list components of a paged
  82.                   file to the screen 
  83.  
  84.                 4.  INCLUDE  or I - list components of a paged
  85.                   file into an include file 
  86.  
  87.                 5.  HELP or H - print a command summary 
  88.  
  89.                 6.  EXIT or X - exit PAGER2 
  90.  
  91.                The case  used  to  enter  these  command  verbs is not
  92.           significant.    The  case  used  to  enter  the  file  names
  93.           referenced  as arguments to the command verbs is significant
  94.           if  the  host  operating  system  distinguishes case in file
  95.           names, as does UNIX (but not MSDOS).  
  96.  
  97.  
  98.           2.1.  PAGE Command 
  99.  
  100.                The PAGE  function  is  used  to  created a paged  file
  101.           from   one  or more component files.  The syntax of the PAGE
  102.           command is: 
  103.  
  104.                PAGE [filename | @include_filename]+ paged_file_name
  105.  
  106.                Two or  more file names may be specified after the PAGE
  107.           verb.   The  last file name is the name of the paged file to
  108.           be  created.  The other file names are the names of files to
  109.           be  placed into the paged file or the names of include files
  110.           from  which  the  names of files to be placed into the paged
  111.           file are to be extracted.  
  112.  
  113.                If the  user prefixes the name of a component file with
  114.           an   atsign  character  (@), the indicated file is processed
  115.           as  an  include  file.   An  include  file  is  a file which
  116.           contains   the   names  of  zero  or  more component  files,
  117.           one   name   per  line  starting in the first column.  Other
  118.  
  119.  
  120.           Richard Conn                                          Page 2
  121.  
  122.  
  123.                                      PAGER2
  124.  
  125.  
  126.           include  files  may   be   referenced   within   an  include
  127.           file    by   prefixing   their   names   with   the   atsign
  128.           character.   Comments  may  be placed within an include file
  129.           by  placing  two  dashes  in  the   first   two columns of a
  130.           line.  The following is an example of an include file: 
  131.  
  132.                    Example                      Comments
  133.                    =======                      ========
  134.           --
  135.           -- This is an include file for        Comment at the beginning
  136.           --  my favorite tool
  137.           --
  138.                                                 Blank lines are allowed
  139.           --
  140.           -- The following include file
  141.           --  contains the names of the         Another comment
  142.           --  Ada source files in compilation
  143.           --  order
  144.           --
  145.           @mytool.cmp
  146.           --
  147.           -- The following are the documentation
  148.           --  files
  149.           --
  150.           mytool.ref
  151.           mytool.doc
  152.           mytool.idx
  153.  
  154.                A single  letter  "P"  may be used rather than the full
  155.           "PAGE"  verb.   An  example  of  the  execution  of the PAGE
  156.           command is: 
  157.  
  158.           PAGER2> page
  159.            PAGE Command requires the name of the paged file and include file
  160.              Syntax: page [@include_file_name|file_name]+ paged_file_name
  161.           PAGER2> p @demo.inc demo.src
  162.            Adding demo.inc -- 8 Lines
  163.            Adding demo1.txt -- 1 Lines
  164.            Adding demo2.txt -- 1 Lines
  165.  
  166.  
  167.           2.2.  UNPAGE Command 
  168.  
  169.                The UNPAGE  function  extracts  the   components   from
  170.           the   indicated  paged   file,  leaving  the  original paged
  171.           file intact.  The syntax of UNPAGE is: 
  172.  
  173.               UNPAGE paged_filename
  174.  
  175.                The single  letter "U" may be used rather than the full
  176.           "UNPAGE"  verb.   An  example of the execution of the UNPAGE
  177.           command is: 
  178.  
  179.  
  180.           Richard Conn                                          Page 3
  181.  
  182.  
  183.                                      PAGER2
  184.  
  185.  
  186.           PAGER2> unpage
  187.            UNPAGE Command requires the name of a paged file
  188.              Syntax: unpage paged_file_name
  189.           PAGER2> u demo.src
  190.            Extracting demo.inc -- 8 Lines
  191.            Extracting demo1.txt -- 1 Lines
  192.            Extracting demo2.txt -- 1 Lines
  193.  
  194.  
  195.           2.3.  LIST Command 
  196.  
  197.                The LIST  function  is  used  to  create  a  text  file
  198.           containing   the  names   of   the  component files within a
  199.           paged file.  The syntax of the LIST command is: 
  200.  
  201.                LIST paged_file_name
  202.  
  203.                The single  letter "L" may be used rather than the full
  204.           "LIST"  verb.   An  example  of  the  execution  of the LIST
  205.           command is: 
  206.  
  207.           PAGER2> list
  208.            LIST Command requires the name of a paged file
  209.              Syntax: list paged_file_name
  210.           PAGER2> list demo.src
  211.            demo.inc -- 8 Lines
  212.            demo1.txt -- 1 Lines
  213.            demo2.txt -- 1 Lines
  214.  
  215.  
  216.           2.4.  INCLUDE Command 
  217.  
  218.                The INCLUDE  command  performs the same function of the
  219.           LIST  command, but it places the output i